How to Use Social Proof Experience Output API - Item Page

Social Proof APIs help to display dynamic social proof messages, the details about how to use these APIs are described in the following sections:

How to obtain API Key

1. Log in to Omnichannel Personalization.
2. On the Omnichannel Personalization Dashboard page, on the left navigation rail, click the customer site name dropdown list and then select the required client name.
3. Click available next to the customer site name dropdown list. The Site-info window is displayed.

   

4. From the Site-info window, copy the API Key and save it to your drive.

Request Call

GET method is used to get the responses.

GET /rrserver/api/engage/spMessages?apiClientKey={apiClientKey}&apiKey={apiKey}&sessionId={sessionId}&placements=list_page&p={pId1|pId2}&userId={userId}&rcs={remoteCookieStoreValue}

Required Parameters:

• All target API parameters

• All experiences API parameters

• All social proof metrics API parameters (apiKey, apiClientKey, productId)

Request Call Parameters

The following parameters are used in social proof API.

Sample Social Proof API Request and Response

API Request

https://recs.richrelevance.com/rrserver/api/engage/spMessages?apiClientKey=xxxxxxxxxxxxxxxx&apiKey=xxxxxxxxxxxxxxxx&s=5oa14nulbga5p2ud3zilg34b18&placements=item_page&categoryId=cycling&p=222264

API Response

{
  "dynamicSocialProofMessages": [
    {
      "experienceId": xxxx,
      "variationId": xxxx,
      "locationSelector": "AboveATC",
      "displayDuration": 5000,
      "displayInformationList": [
        {
          "productId": "xxx_xxx-xxxx-xxxx-xxx",
          "messageList": [
            {
              "count": 576,
              "finalMessage": "576 people purchased today",
              "threshold": 1,
              "order": 1,
              "messageText": "@usercount people purchased today"
            },
            {
              "count": 612,
              "finalMessage": "612 people have added to cart today",
              "threshold": 1,
              "order": 2,
              "messageText": "@usercount people have added to cart today"
            },
            {
              "count": 16119,
              "finalMessage": "16119 people viewed today",
              "threshold": 1,
              "order": 3,
              "messageText": "@usercount people viewed today"
            }
          ]
        }
      ],
      "importance": 1,
      "multipleMessagesEnabled": true
    }
  ],
  "error": null
}

Response Metrics Description

• experienceId: It is the unique ID available for an experience.

  For example: https://qa.richrelevance.com/engage/socialProof.jsp#/message/8060 (In this URL, 8060 represents the experience ID).

• variationId: It is the unique ID available for a variation under the experience.

  For example: https://qa.richrelevance.com/engage/socialProof.jsp#/message/8060/5385 (In this URL, 5385 represents the variation ID.

• locationSelector: It is the selector of the element for which the social proof message is inserted on the page. To place the message at the right location, it is important to identify the right UI component & identifier and use that parameter for inserting the social proof message. For a given location selector, the highest importance social proof experience will be considered.

• displayDuration: It is the duration for each social proof message specified in milliseconds when multiple messages are enabled. Default value is 5000 milli seconds (5 seconds).

• count: This is the user count or event count selected as part of the social proof experience setup.

• messageText: This is the message text defined as part of social proof experience for each message type (metric & interval).

• threshold or range: A threshold or range can be configured as part of the social proof experience for each message type (metric & interval).

  When threshold is selected:

  • A threshold value is defined as part of the message type and interval will be displayed.

  When range is selected:

  • Both minimum and maximum values can be defined as part of the message type and interval will be displayed.

  • If both minimum and maximum values are defined, the message displays: Minimum: <min value>, Maximum: <max value>.

  • If only the minimum value is defined, the message will only display the minimum value and the maximum value will be omitted.

• order: This is the order in which social proof messages are to be displayed. (In case of multiple messages enabled). In case of multiple messages disabled, it will pick the message with the highest order that meets the threshold.

• Final message: This is the final social proof output message. It is based on the text with user count or event count parameter replaced by count value.

Response Codes Description

How Social Proof Experience Output API Works

Using social proof setup configurations for server side or mobile app through an API to know what to show in a given variation, so that the user only needs to define how to display the social proof message.

• Focuses on active Social Proof experiences - those currently active or Evergreen.

• The Importance of the experience plays a key role when there are multiple conflicting experiences in a given context.

  • Automatically picks the experience with highest Importance when multiple experiences share the same location selector.

  • If the location selector is null, It picks the highest importance experience and show it as part of the response.

  • If the location selector and importance are the same, then it picks a message randomly.

• Identifies the right experience/variation based on context and segment parameters passed from the API call.

• Identifies the threshold based on the user count or event count parameter from the message text.

• Identifies the event count or user count through the SP API for the given product and identify the final text to be shown.

• Perform the following action when the “Display Multiple Messages” option is enabled or disabled:

  • If the ''Display Multiple Messages'' option is enabled, then identify all the messages that are meeting the threshold and defined to show all the messages as part of the response. This includes the following:

    • Message Text, Priority, and display Interval

    • Event count/User count based on what is defined in the text.

    OR

  • If the ''Display Multiple Messages'' option is disabled (single message scenario), then identify the highest priority message meeting the threshold that is defined to show the message as part of the response. This includes the following:

    • Message Text

    • Event count/User count based on what is defined in the text.

• For category/list page templates, multiple product IDs can be passed. However multiple messages cannot be provided for a single product when multiple products are passed. It is a limitation of social proof API.

  For more details about how to set up the social proof experience, refer to Social Proof User Guide.